uu**coding is a way of converting a binary file into printable text for transmission over an electronic medium. This is the standard when dealing with unix™ based operating systems. The acronym ‘uu’ means unix-to-unix, and the utilities uuencode and uudecode are usually found wherever the unix-to-unix copy (UUCP) program is on your unix system. uuencoding converts a binary file to printable text, and uudecoding coverts the text file back to binary. Typically encoded files are 1/3 larger than the original binaries.
2.0 What’s in this package?
This package contains the resources and C glue to include in your own Macintosh™ programs to do uu**coding. There should be the following files: “uu**code” resource file, “UUGlue.c” glue C source, “UUGlue.h” glue C prototypes, “UUIntf.p” glue Pascal source, some Pascal and C sample encoders by Leonard Rosenthol, and “uu**code usage” (this document). Only distribute the original archive containing all of the above mentioned files.
3.0 How do you use it?
The first step is to familiarize yourself with the provided routines. The uu**coding engine, residing in the ‘UENG’ resource, contains routines for encoding and decoding. See the glue routines in UUGlue.c for more information (or UUIntf.p for Leonard's Pascal glue).
Once you know what the routines do, you can start designing your program around them. You’ll need to call the glue routine “UULoad” from your program before using any of the routines, and call “UUnload” afterwards. “UULoad” loads the UENG 128 resource, and the HEXA 128 resource which contains the uuencoding table. The table is not needed for decoding.
You need to copy the UENG and HEXA resources into your application to be able to use the uu**coding engine. I also ask that the ‘vers’ resource be copied, given a unique id.
Your program must open the input/output files, allocate buffers, and do some preprocessing. You get to tell the uuencode() and uudecode() routines how much space to use. They require contiguous free space to operate.
The preprocessing differs between encoding and decoding. When encoding, your program is responsible for adding the epilogue and prologue (begin and end) statements. A uuencode file looks something like:
begin 0755 filename
...data...
end
where ‘begin’ is the start token on a new line, ‘0755’ is the unix permission mode for the file, and ‘filename’ is the file’s name. Your program might look something like this if you used standard i/o libraries:
The "UpdateProcedure" is a routine that you specify which the uu**code routines call at specified times. If you pass a NIL value, no update procedure will be called. The prototype of the UpdateProcedure in C looks like this:
pascal OSErr UpdateProcedure(int InputFileRefNum, int OutputFileRefNum);
Your routine is passed the input file's reference number and the output file's reference number. You should return an error code, which exits cleanly, or 0. You can do whatever processing you like in the procedure, but beware of unclean exiting (you will leave the buffers allocated and might run out of memory if you continue). Both uu**code routines call the UpdateProcedure when the output buffer is full, BEFORE it is written to disk. There are two things you might want to do in the UpdateProcedure. First, give the user feedback with regards to progress. Second, abort coding. Feedback is best implemented in your program by looking at the current mark of your input file. That way you know how much you have read. You guess at how far you must go. You know exact sizes when encoding, but decoding is not deterministic without pre-parsing since any data can be before the 'begin' statement or after the 'end' statement. (If you want to track the output status, talk to me and I'll tell you why you don't really want to do it.) Abort is best handled by watching keyboard events and checking for 'CMD-.' (be nice - support international keyboards by using charCode and not keyCode). Return an appropriate error, like 128, if the user aborts.
4.0 Licensing Agreement
Bernhard S. Wieser and Octavian Micro Development, grant use of their uu**coding engine and glue, known as the software, pending agreement of interested parties to the following terms.
If the software is to be used by one person at one time within their own personal and private programs, visible credit must be given to Bernhard S. Wieser and Octavian Micro Development.
If the software is to be used in a program distributed as “freeware” explicit written permission must be obtained, and visible credit must be given to Bernhard S. Wieser and Octavian Micro Development, before release of the “freeware”.
If the software is to be used in in-house software by a business, or in a program distributed as “shareware”, or in or with a commercial product, a licensing fee must be negotiated and paid to Octavian Micro Development before release of said software, explicit written permission must be obtained, and visible credit must be given to Bernhard S. Wieser and Octavian Micro Development.
The user, or client, release Bernhard S. Wieser and Octavian Micro Development of any responsibility by damages caused directly or indirectly by the software.
5.0 Support
Octavian Micro Development will provide support depending on the client’s standing. Source code to UUTool 2.0 is available for $20. Updates for all software will only be mailed to registered users; disk and SASE should be included. All monies should be in US funds. Our address:
Octavian Micro Development
10516 Bradbury Dr. S.W.
Calgary, Alberta, Canada
T2W1A6
If you have any questions, feel free to call (403)259-4907 or (403)252-3910 and ask for Bernie.
Macintosh™ is a registered trademark of Apple Computer Inc.
UNIX™ is a registered trademark of AT&T Information Systems.
